E.g., the function and parameter are named poorly here, and so comments need to do all the heavy lifting:

# function to convert temperature from Fahrenheit to Celsius scale
# temp is the temperature in Fahrenheit
def unit_converter(temp: float) -> float:
    pass

Contrast it with this:

def fahrenheit_to_celsius(temp_fahrenheit: float) -> float:
    pass

No need for a comment here!

Examples:

• In a nested loop, using j for outer and i for inner loop index is confusing!

for j in range(len(arr)):
    for i in range(len(arr[j])):

• tmp shouldn’t be used to store objects that are not temporary
• retVal shouldn’t be used for objects not returned from a function

All variables are temporary in some sense. Calling one tmp is inviting carelessness.

# generic name
if right < left:
    tmp = right
    right = left
    left = tmp

# more descriptive
if right < left:
    old_right = right
    right = left
    left = old_right

For example, these names are inconsistent since the reader can’t safely assume that the name size means the same thing throughout the program.

# context-1: `size` stands for number of memory bytes
size = len(x.encode('utf-8'))  # bytes

# context-2: `size` stands for number of elements
size = len(a)  # length

# context-1:
size = len(x.encode('utf-8'))

# context-2:
length = len(a)

You can typically find a middle ground between too short and too long names.

# not ideal - too imprecise
d

# okay - can use more precision
days

# good - middle ground
days_since_last_accident

# not ideal - unnecessarily precise
days_since_last_accident_floor_4_lab_23

# ...

E.g., here is a text editor class method to get position of a character:

def get_char_position(x: int, y: int):
    pass

How I interpret: “x and y refer to pixel positions for a character.”

In reality: “x and y refer to line of text and character position in that line.”

You can avoid such misinterpretation with better names:

def get_char_position(line_index: int, char_index: int):
    pass

E.g. nn and nnn are easy to be confused and such confusion can lead to painful bugs.

# bad
n = x
nn = x ** 2
nnn = x ** 3

# good
n = x
n_square = x ** 2
n_cube = x ** 3

E.g., this function uses a and f parameters to represent an array and a function.

# bad
def array_map(a, f):
    pass

# good
def array_map(arr, fun):
    pass

If needed, it wouldn’t be easy either to search for and/or to rename these parameters in the codebase because searching for a or f would flag all as and fs (api, file, etc.).

Instead, if more descriptive identifiers are used, both search and replace operations will be straightforward. In general, searchability of a name indexes how generic it is.

For example, Python convention is to use PascalCase for class names and snake_case for variables.

# non-conventional
class playerentity:
    def __init__(self):
        self.HairColor = ""

# conventional
class PlayerEntity:
    def __init__(self):
        self.hair_color = ""

In general, use positive terms for Booleans since they are easier to process.

# double negation - difficult
is_firewall_disabled = False

# better
is_firewall_enabled = True

E.g., consider variables that store data in different data structures or cloud services:

# bad
bonuses_pd  # pandas DataFrame
bonuses_pl  # polars DataFrame

aws_s3_url  # AWS bucket
gcp_url     # GCP bucket

# good
bonuses    # data structure independent

bucket_url # cloud service independent

For example, let’s say your class has the .get_means() method.

• In its initial implementation, it used to return precomputed mean values.
• In its current implementation, it computes the mean values on the fly.

Therefore, it is misleading to continue to call it a getter method, and it should be renamed to (e.g.) .compute_means().

If you are writing a function to generate a time-stamp, discussing the following function verbally would be challenging.

# generate year month date hour minute second
genymdhms()

This is a much better (and pronounceable) alternative:

generate_timestamp()

Additionally, avoid naming separate entities with homonyms.

Discussing entities named waste and waist is inevitably going to lead to confusion.

E.g., two similar methods here have different names across Python classes:

CreditCardAccount().retrieve_expenditure()
DebitCardAccount().fetch_expenditure()

Both of these methods should either be named .retrieve_expenditure() or .fetch_expenditure().

• Don’t use slang. You can’t assume current or future developers to be familiar with them. E.g. exit() is better than hit_the_road().

• Avoid unintended meanings. Do your due diligence to check dictionaries (especially Urban dictionary!) if the word has unintended meaning. E.g. cumulative_sum() is a better function name than cumsum().

• Avoid imprecise opposites, since they can be confusing. E.g. parameter combination begin/last is worse than either begin/end or first/last.

• Don’t use hard-to-distinguish character pairs in names (e.g., l and I, O and 0, etc.). With certain fonts, firstl and firstI look identical.

• Don’t misspell to save a few characters. Remembering spelling is difficult, and remembering correct misspelling even more so. E.g. don’t use hilite instead of highlight. The benefit is not worth the cost here.

• Don’t use commonly misspelled words in English. Using such names for variables can, at minimum, slow you down, or, at worst, increase the possibility of making an error. E.g. is it accumulate, accummulate, acumulate, or acummulate?!

• Don’t use numeric suffixes in names to specify levels. E.g. variable names level1, level2, level3 are not as informative as beginner, intermediate, advanced.

• Don’t allow multiple English standards. E.g. using both American and British English standards would have you constantly guessing if the variable is named (e.g.) centre or center. Adopt one standard and stick to it.

• Don’t use similar names for entities with different meanings. E.g. patientRecs and patientReps are easily confused because they are so similar. There should be at least two-letter difference: patientRecords and patientReports.

• Don’t use uncommon English words. Stick to common parlance that most developers understand. E.g. start_process() is better than commence_process(), get_list() is better than procure_list(), find_user() is better than ascertain_user().

Consider a function to extract a table of regression estimates for a statistical model. For convenience, it also allows sorting the table by estimate.

def mystery_function(model, sort="asc"):
    # code to extract estimates from model
    # code to sort table
    pass

def extract_estimates(model):
    # code to extract estimates from model
    pass

def sort_estimates(table, sort="asc"):
    # code to sort table
    pass

Functions with and or or in their names are dead giveaways that they don’t follow the Unix philosophy.

Consider a function that converts Markdown or HTML documents to PDF.

def convert_to_pdf(file, is_markdown=False):
    if is_markdown:
        # code to convert Markdown to PDF
        pass
    
    if not is_markdown:
        # code to convert HTML to PDF
        pass

def convert_md_to_pdf(file):
    # code to convert Markdown to PDF
    pass

def convert_html_to_pdf(file):
    # code to convert HTML to PDF
    pass

• Intent-revealing names make the code easier to read.

• Trying to find good names forces you to detach from the problem-solving mindset and to focus on the bigger picture that motivates this change. This is critical for thoughtful software design.

• Searching for precise names requires clarity, and seeking such clarity improves your own understanding of the code.

• Naming precisely and consistently reduces ambiguities and misunderstandings, reducing the possibility of bugs.

• Good names reduce the need for documentation.

• Consistent naming reduces cognitive overload for the developers and makes the code more maintainable.